IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/RWWString.z/RWWString

Text File | 1998-10-30 | 49.4 KB | 1,123 lines

RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWWString - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/wstring.h>



              RWWString a;




DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     Class RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg offers very powerful and convenient facilities for
     manipulating wide character strings.  This string class manipulates wwwwiiiiddddeeee
     cccchhhhaaaarrrraaaacccctttteeeerrrrssss of the fundamental type wwwwcccchhhhaaaarrrr____tttt.  These characters are
     generally two or four bytes, and can be used to encode richer code sets
     than the classic "cccchhhhaaaarrrr" type.  Because wwwwcccchhhhaaaarrrr____tttt characters are all the
     same size, indexing is fast.  Conversion to and from multibyte and ASCII
     forms are provided by the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg constructors, and by the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg
     member functions iiiissssAAAAsssscccciiiiiiii(((()))), ttttooooAAAAsssscccciiiiiiii(((()))), and ttttooooMMMMuuuullllttttiiiiBBBByyyytttteeee(((()))).  Stream
     operations implicitly translate to and from the multibyte stream
     representation.  That is, on output, wide character strings are converted
     into multibyte strings, while on input they are converted back into wide
     character strings.  Hence, the external representation of wide character
     strings is usually as multibyte character strings, saving storage space
     and making interfaces with devices (which usually expect multibyte
     strings) easier.  RRRRWWWWWWWWSSSSttttrrrriiiinnnnggggs tolerate embedded nulls.  Parameters of type
     "ccccoooonnnnsssstttt wwwwcccchhhhaaaarrrr____tttt****" must not be passed a value of zero.  This is detected in
     the debug version of the library.  The class is implemented using a
     technique called ccccooooppppyyyy oooonnnn wwwwrrrriiiitttteeee.  With this technique, the copy
     constructor and assignment operators still reference the old object and
     hence are very fast.  An actual copy is made only when a "write" is
     performed, that is if the object is about to be changed.  The net result
     is excellent performance, but with easy-to-understand copy semantics.  A
     separate RRRRWWWWWWWWSSSSuuuubbbbSSSSttttrrrriiiinnnngggg class supports substring extraction and
     modification operations.

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     Simple

EEEExxxxaaaammmmpppplllleeee
              #include <rw/rstream.h>
          #include <rw/wstring.h>
          main(){
           RWWString a(L"There is no joy in Beantown");
           a.subString(L"Beantown") = L"Redmond";
           cout << a << endl;
           return 0;
          }




                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     PPPPrrrrooooggggrrrraaaammmm oooouuuuttttppppuuuutttt::::

              There is no joy in Redmond.



EEEEnnnnuuuummmmeeeerrrraaaattttiiiioooonnnnssss




              enum RWWString::caseCompare { exact, ignoreCase };


     Used to specify whether comparisons, searches, and hashing functions
     should use case sensitive (eeeexxxxaaaacccctttt) or case-insensitive (iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee)
     semantics..

              enum RWWString::multiByte_ { multiByte };


     Allow conversion from multibyte character strings to wide character
     strings.  See constructor below.

              enum RWWString::ascii_ {ascii };


     Allow conversion from ASCII character strings to wide character strings.
     See constructor below.

PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg();


     Creates a string of length zero (the null string).

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const wchar_t* cs);


     Creates a string from the wide character string ccccssss.  The created string
     will ccccooooppppyyyy the data pointed to by ccccssss, up to the first terminating null.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const wchar_t* cs, size_t N);


     Constructs a string from the character string ccccssss.  The created string
     will ccccooooppppyyyy the data pointed to by ccccssss.  Exactly NNNN characters are copied,
     iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be
     at least NNNN**** ssssiiiizzzzeeeeooooffff((((wwwwcccchhhhaaaarrrr____tttt)))) bytes or NNNN wide characters long.






                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(RWSize_T ic);


     Creates a string of length zero (the null string).  The string's ccccaaaappppaaaacccciiiittttyyyy
     (that is, the size it can grow to without resizing) is given by the
     parameter iiiicccc.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const RWWString& str);


     Copy constructor.  The created string will ccccooooppppyyyy ssssttttrrrr's data.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const RWWSubString& ss);


     Conversion from sub-string.  The created string will ccccooooppppyyyy the substring
     represented by ssssssss.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(char c);


     Constructs a string containing the single character cccc.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(char c, size_t N);


     Constructs a string containing the character cccc repeated NNNN times.

              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const char* mbcs, multiByte_ mb);


     Construct a wide character string from the multibyte character string
     contained in mmmmbbbbccccssss.  The conversion is done using the Standard C library
     function ::::::::mmmmbbbbssssttttoooowwwwccccssss(((()))).  This constructor can be used as follows:

              RWWString a("306374315313306374", multiByte);







              RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg(const char* acs, ascii_ asc);


     Construct a wide character string from the ASCII character string
     contained in aaaaccccssss.  The conversion is done by simply stripping the high-
     order bit and, hence, is much faster than the more general constructor
     given immediately above.  For this conversion to be successful, you must
     be certain that the string contains only ASCII characters.  This can be
     confirmed (if necessary) using RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg::::::::iiiissssAAAAsssscccciiiiiiii(((()))).  This constructor



                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     can be used as follows:

                 RWWString a("An ASCII character string", ascii);




             RWWString(const char* cs, size_t N, multiByte_ mb);
             RWWString(const char* cs, size_t N, ascii__ asc);


     These two constructors are similar to the two constructors immediately
     above except that they copy exactly NNNN characters, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd
     nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be at least NNNN bytes long.

TTTTyyyyppppeeee CCCCoooonnnnvvvveeeerrrrssssiiiioooonnnn
              operator
          ccccoooonnnnsssstttt wwwwcccchhhhaaaarrrr____tttt****() const;


     Access to the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg's data as a null terminated wide string.  This
     datum is owned by the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg and may not be deleted or changed.  If
     the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg object itself changes or goes out of scope, the pointer
     value previously returned wwwwiiiillllllll become invalid.  While the string is
     null-terminated, note that its lllleeeennnnggggtttthhhh is still given by the member
     function lllleeeennnnggggtttthhhh(((()))).  That is, it may contain embedded nulls.

AAAAssssssssiiiiggggnnnnmmmmeeeennnntttt OOOOppppeeeerrrraaaattttoooorrrrssss
              RWWString&
          ooooppppeeeerrrraaaattttoooorrrr====(const char* cs);


     Assignment operator.  Copies the null-terminated character string pointed
     to by ccccssss into self.  Returns a reference to self.

              RWWString&
          ooooppppeeeerrrraaaattttoooorrrr====(const RWWString& str);


     Assignment operator.  The string will ccccooooppppyyyy ssssttttrrrr's data.  Returns a
     reference to self.

              RWWString&
          ooooppppeeeerrrraaaattttoooorrrr====(const RWWSubString& sub);


     Assignment operator.  The string will ccccooooppppyyyy ssssuuuubbbb's data.  Returns a
     reference to self.

              RWWString&
          ooooppppeeeerrrraaaattttoooorrrr++++====(const wchar_t* cs);




                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Append the null-terminated character string pointed to by ccccssss to self.
     Returns a reference to self.

              RWWString&
          ooooppppeeeerrrraaaattttoooorrrr++++====(const RWWString& str);


     Append the string ssssttttrrrr to self.  Returns a reference to self.

IIIInnnnddddeeeexxxxiiiinnnngggg OOOOppppeeeerrrraaaattttoooorrrrssss
              wchar_t&
          ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](size_t i);
          wchar_t
          ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](size_t i) const;


     Return the iiiith character.  The first variant can be used as an lvalue.
     The index iiii must be between 0 and the length of the string less one.
     Bounds checking is performed -- if the index is out of range then an
     exception of type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will be thrown.

              wchar_t&
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t i);
          wchar_t
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t i) const;


     Return the iiiith character.  The first variant can be used as an lvalue.
     The index iiii must be between 0 and the length of the string less one.
     Bounds checking is performed if the pre-processor macro RRRRWWWWBBBBOOOOUUUUNNNNDDDDSSSS____CCCCHHHHEEEECCCCKKKK
     has been defined before including <<<<rrrrwwww////wwwwssssttttrrrriiiinnnngggg....hhhh>>>>.  In this case, if the
     index is out of range, then an exception of type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will be
     thrown.

              RWWSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t start, size_t len);
          const RWWSubString
          ooooppppeeeerrrraaaattttoooorrrr(((())))(size_t start, size_t len) const;


     Substring operator.  Returns an RRRRWWWWWWWWSSSSuuuubbbbSSSSttttrrrriiiinnnngggg of self with length lllleeeennnn,
     starting at index ssssttttaaaarrrrtttt.  The first variant can be used as an lvalue.
     The sum of ssssttttaaaarrrrtttt plus lllleeeennnn must be less than or equal to the string
     length.  If the library was built using the RRRRWWWWDDDDEEEEBBBBUUUUGGGG flag, and ssssttttaaaarrrrtttt and
     lllleeeennnn are out of range, then an exception of type RRRRWWWWBBBBoooouuuunnnnddddssssEEEErrrrrrrr will be
     thrown.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              RWWString&
          aaaappppppppeeeennnndddd(const wchar_t* cs);





                                                                        PPPPaaaaggggeeee 5555






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Append a copy of the null-terminated wide character string pointed to by
     ccccssss to self.  Returns a reference to self.

              RWWString&
          aaaappppppppeeeennnndddd(const wchar_t* cs, size_t N,);


     Append a copy of the wide character string ccccssss to self.  Exactly NNNN wide
     characters are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer
     pointed to by ccccssss must be at least NNNN****ssssiiiizzzzeeeeooooffff((((wwwwcccchhhhaaaarrrr____tttt)))) bytes long.  Returns
     a reference to self.

              RWWString&
          aaaappppppppeeeennnndddd(const RWWString& cstr);


     Append a copy of the string ccccssssttttrrrr to self.  Returns a reference to self.

              RWWString&
          aaaappppppppeeeennnndddd(const RWWString& cstr, size_t N);


     Append the first NNNN characters or the length of ccccssssttttrrrr (whichever is less)
     of ccccssssttttrrrr to self.  Returns a reference to self.

              size_t
          bbbbiiiinnnnaaaarrrryyyySSSSttttoooorrrreeeeSSSSiiiizzzzeeee() const;


     Returns the number of bytes necessary to store the object using the
     global function:

                 RWFile& operator<<(RWFile&, const RWWString&);



              size_t
          ccccaaaappppaaaacccciiiittttyyyy() const;


     Return the current capacity of self.  This is the number of characters
     the string can hold without resizing.

              size_t
          ccccaaaappppaaaacccciiiittttyyyy(size_t capac);


     Hint to the implementation to change the capacity of self to ccccaaaappppaaaacccc.
     Returns the actual capacity.






                                                                        PPPPaaaaggggeeee 6666






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              int
          ccccoooollllllllaaaatttteeee(const RWWString& str) const;
          int
          ccccoooollllllllaaaatttteeee(const wchar_t*   str) const;


     Returns an int less then, greater than, or equal to zero, according to
     the result of calling the POSIX function ::::::::wwwwssssccccoooollllllll(((()))) on self and the
     argument ssssttttrrrr.  This supports locale-dependent collation.

              int
          ccccoooommmmppppaaaarrrreeeeTTTToooo(const RWWString& str,
                    caseCompare = RWWString::exact) const;
          int
          ccccoooommmmppppaaaarrrreeeeTTTToooo(const wchar_t*   str,
                    caseCompare = RWWString::exact) const;


     Returns an int less than, greater than, or equal to zero, according to
     the result of calling the Standard C library function ::::::::mmmmeeeemmmmccccmmmmpppp(((()))) on self
     and the argument ssssttttrrrr.  Case sensitivity is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee
     argument, and may be RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt or RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(const RWWString& cs,
                   caseCompare = RWWString::exact) const;
          RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(const wchar_t* str,
                   caseCompare = RWWString::exact) const;


     Pattern matching.  Returns TTTTRRRRUUUUEEEE if  ccccssss occurs in self.  Case sensitivity
     is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument, and may be RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt or
     RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::iiiiggggnnnnoooorrrreeeeCCCCaaaasssseeee.

              const wchar_t*
          ddddaaaattttaaaa() const;


     Access to the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg's data as a null terminated string.  This datum
     is owned by the RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg and may not be deleted or changed.  If the
     RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg object itself changes or goes out of scope, the pointer value
     previously returned wwwwiiiillllllll become invalid.  While the string is null-
     terminated, note that its lllleeeennnnggggtttthhhh is still given by the member function
     lllleeeennnnggggtttthhhh(((()))).  That is, it may contain embedded nulls.

              size_t
          ffffiiiirrrrsssstttt(wchar_t c) const;


     Returns the index of the first occurrence of the wide character cccc in
     self.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such character or if there is an



                                                                        PPPPaaaaggggeeee 7777






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     embedded null prior to finding cccc.

              size_t
          ffffiiiirrrrsssstttt(wchar_t c, size_t) const;


     Returns the index of the first occurrence of the wide character cccc in
     self.  Continues to search past embedded nulls.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there
     is no such character.

              size_t
          ffffiiiirrrrsssstttt(const wchar_t* str) const;


     Returns the index of the first occurrence in self of any character in
     ssssttttrrrr.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no match or if there is an embedded
     null prior to finding any character from ssssttttrrrr.

              size_t
          ffffiiiirrrrsssstttt(const wchar_t* str, size_t N) const;


     Returns the index of the first occurrence in self of any character in
     ssssttttrrrr.  Exactly NNNN characters in ssssttttrrrr are checked iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd
     nnnnuuuullllllllssss so ssssttttrrrr must point to a buffer containing at least NNNN wide
     characters.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no match.

              unsigned
          hhhhaaaasssshhhh(caseCompare = RWWString::exact) const;


     Returns a suitable hash value.

              size_t
          iiiinnnnddddeeeexxxx(const wchar_t* pat,size_t i=0,
                caseCompare = RWWString::exact) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWWString& pat,size_t i=0,
                caseCompare = RWWString::exact) const;


     Pattern matching.  Starting with index iiii, searches for the first
     occurrence of ppppaaaatttt in self and returns the index of the start of the
     match.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such pattern.  Case sensitivity is
     according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument; it defaults to RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt.

              size_t
          iiiinnnnddddeeeexxxx(const wchar_t* pat, size_t patlen,size_t i,
                caseCompare) const;
          size_t
          iiiinnnnddddeeeexxxx(const RWWString& pat, size_t patlen,size_t i,
                caseCompare) const;



                                                                        PPPPaaaaggggeeee 8888






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Pattern matching.  Starting with index iiii, searches for the first
     occurrence of the first ppppaaaattttlllleeeennnn characters from ppppaaaatttt in self and returns
     the index of the start of the match.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such
     pattern.  Case sensitivity is according to the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument.

              RWWString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const wchar_t* cs);


     Insert a copy of the null-terminated string ccccssss into self at position ppppoooossss.
     Returns a reference to self.

              RWWString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const wchar_t* cs, size_t N);


     Insert a copy of the first NNNN wide characters of ccccssss into self at position
     ppppoooossss.  Exactly NNNN wide characters are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.
     Hence, the buffer pointed to by ccccssss must be at least NNNN****ssssiiiizzzzeeeeooooffff((((wwwwcccchhhhaaaarrrr____tttt))))
     bytes long.  Returns a reference to self.

              RWWString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const RWWString& str);


     Insert a copy of the string ssssttttrrrr into self at position ppppoooossss.  Returns a
     reference to self.

              RWWString&
          iiiinnnnsssseeeerrrrtttt(size_t pos, const RWWString& str, size_t N);


     Insert a copy of the first NNNN wide characters or the length of ssssttttrrrr
     (whichever is less) of ssssttttrrrr into self at position ppppoooossss.  Returns a
     reference to self.

              RWBoolean
          iiiissssAAAAsssscccciiiiiiii() const;


     Returns TTTTRRRRUUUUEEEE if it is safe to perform the conversion ttttooooAAAAsssscccciiiiiiii(((()))) (that is,
     if all characters of self are ASCII characters).

              RWBoolean
          iiiissssNNNNuuuullllllll() const;


     Returns TTTTRRRRUUUUEEEE if this string has zero length (iiii....eeee...., the null string).

              size_t
          llllaaaasssstttt(wchar_t c) const;




                                                                        PPPPaaaaggggeeee 9999






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Returns the index of the last occurrence in the string of the wide
     character cccc.  Returns RRRRWWWW____NNNNPPPPOOOOSSSS if there is no such character.

              size_t
          lllleeeennnnggggtttthhhh() const;


     Return the number of characters in self.

              RWWString&
          pppprrrreeeeppppeeeennnndddd(const wchar_t* cs);


     Prepend a copy of the null-terminated wide character string pointed to by
     ccccssss to self.  Returns a reference to self.

              RWWString&
          pppprrrreeeeppppeeeennnndddd(const wchar_t* cs, size_t N,);


     Prepend a copy of the character string ccccssss to self.  Exactly NNNN characters
     are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to
     by ccccssss must be at least NNNN****ssssiiiizzzzeeeeooooffff((((wwwwcccchhhhaaaarrrrtttt____tttt)))) bytes long.  Returns a
     reference to self.

              RWWString&
          pppprrrreeeeppppeeeennnndddd(const RWWString& str);


     Prepends a copy of the string ssssttttrrrr to self.  Returns a reference to self.

              RWWString&
          pppprrrreeeeppppeeeennnndddd(const RWWString& cstr, size_t N);


     Prepend the first NNNN wide characters or the length of ccccssssttttrrrr (whichever is
     less) of ccccssssttttrrrr to self.  Returns a reference to self.

              istream&
          rrrreeeeaaaaddddFFFFiiiilllleeee(istream& s);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until EEEEOOOOFFFF is reached.  The input stream is treated as a sequence
     of multibyte characters, each of which is converted to a wide character
     (using the Standard C library function mmmmbbbbttttoooowwwwcccc(((())))) before storing.  Null
     characters are treated the same as other characters.

              istream&
          rrrreeeeaaaaddddLLLLiiiinnnneeee(istream& s, RWBoolean skipWhite = TRUE);





                                                                       PPPPaaaaggggeeee 11110000






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Reads characters from the input stream ssss, replacing the previous contents
     of self, until a newline (or an EEEEOOOOFFFF) is encountered. The newline is
     removed from the input stream but is not stored.  The input stream is
     treated as a sequence of multibyte characters, each of which is converted
     to a wide character (using the Standard C library function mmmmbbbbttttoooowwwwcccc(((()))))
     before storing.  Null characters are treated the same as other
     characters.  If the sssskkkkiiiippppWWWWhhhhiiiitttteeee argument is TTTTRRRRUUUUEEEE, then whitespace is
     skipped (using the iiiioooossssttttrrrreeeeaaaammmm library manipulator wwwwssss) before saving
     characters.

              istream&
          rrrreeeeaaaaddddSSSSttttrrrriiiinnnngggg(istream& s);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until an EEEEOOOOFFFF or null terminator is encountered.  The input
     stream is treated as a sequence of multibyte characters, each of which is
     converted to a wide character (using the Standard C library function
     mmmmbbbbttttoooowwwwcccc(((())))) before storing.

              istream&
          rrrreeeeaaaaddddTTTTooooDDDDeeeelllliiiimmmm(istream&, wchar_t delim=(wchar_t)'0);


     Reads characters from the input stream ssss, replacing the previous contents
     of self, until an EEEEOOOOFFFF or the delimiting character ddddeeeelllliiiimmmm is encountered.
     The delimiter is removed from the input stream but is not stored.  The
     input stream is treated as a sequence of multibyte characters, each of
     which is converted to a wide character (using the Standard C library
     function mmmmbbbbttttoooowwwwcccc(((())))) before storing.  Null characters are treated the same
     as other characters.

              istream&
          rrrreeeeaaaaddddTTTTooookkkkeeeennnn(istream& s);


     Whitespace is skipped before storing characters into wide string.
     Characters are then read from the input stream ssss, replacing previous
     contents of self, until trailing whitespace or an EEEEOOOOFFFF is encountered. The
     trailing whitespace is left on the input stream.  Only ASCII whitespace
     characters are recognized, as defined by the standard C library function
     iiiissssssssppppaaaacccceeee(((()))).  The input stream is treated as a sequence of multibyte
     characters, each of which is converted to a wide character (using the
     Standard C library function mmmmbbbbttttoooowwwwcccc(((())))) before storing.

              RWWString&
          rrrreeeemmmmoooovvvveeee(size_t pos);


     Removes the characters from the position ppppoooossss, which must be no greater
     than lllleeeennnnggggtttthhhh(((()))), to the end of string.  Returns a reference to self.




                                                                       PPPPaaaaggggeeee 11111111






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWWString&
          rrrreeeemmmmoooovvvveeee(size_t pos, size_t N);


     Removes NNNN wide characters or to the end of string (whichever comes first)
     starting at the position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))).
     Returns a reference to self.

              RWWString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N, const wchar_t* cs);


     Replaces NNNN wide characters or to the end of string (whichever comes
     first) starting at position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))),
     with a copy of the null-terminated string ccccssss.  Returns a reference to
     self.

              RWWString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N1,const wchar_t* cs, size_t N2);


     Replaces NNNN1111 characters or to the end of string (whichever comes first)
     starting at position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a
     copy of the string ccccssss.  Exactly NNNN2222 characters are copied, iiiinnnncccclllluuuuddddiiiinnnngggg aaaannnnyyyy
     eeeemmmmbbbbeeeeddddddddeeeedddd nnnnuuuullllllllssss.  Hence, the buffer pointed to by ccccssss must be at least
     NNNN2222****ssssiiiizzzzeeeeooooffff((((wwwwcccchhhhaaaarrrrtttt____tttt)))) bytes long.  Returns a reference to self.

              RWWString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N, const RWWString& str);


     Replaces NNNN characters or to the end of string (whichever comes first)
     starting at position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a
     copy of the string ssssttttrrrr.  Returns a reference to self.

              RWWString&
          rrrreeeeppppllllaaaacccceeee(size_t pos, size_t N1,
                  const RWWString& str, size_t N2);


     Replaces NNNN1111 characters or to the end of string (whichever comes first)
     starting at position ppppoooossss, which must be no greater than lllleeeennnnggggtttthhhh(((()))), with a
     copy of the first NNNN2222 characters, or the length of ssssttttrrrr (whichever is
     less), from ssssttttrrrr.  Returns a reference to self.

              void
          rrrreeeessssiiiizzzzeeee(size_t n);


     Changes the length of self, adding blanks (iiii....eeee...., LLLL'''' '''') or truncating as
     necessary.




                                                                       PPPPaaaaggggeeee 11112222






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWWSubString
          ssssttttrrrriiiipppp(stripType s = RWWString::trailing, wchar_t c = L' '); const RWWSubString
          ssssttttrrrriiiipppp(stripType s = RWWString::trailing, wchar_t c = L' ')
                const;


     Returns a substring of self where the character cccc has been stripped off
     the beginning, end, or both ends of the string.  The first variant can be
     used as an lvalue.  The enum ssssttttrrrriiiippppTTTTyyyyppppeeee can take values:






     ssssttttrrrriiiippppTTTTyyyyppppeeee MMMMeeeeaaaannnniiiinnnngggg


     lllleeeeaaaaddddiiiinnnngggg Remove characters at beginning


     ttttrrrraaaaiiiilllliiiinnnngggg Remove characters at end


     bbbbooootttthhhh Remove characters at both ends


          RWWSubString
          ssssuuuubbbbSSSSttttrrrriiiinnnngggg(const wchar_t* cs, size_t start=0,
                    caseCompare = RWWString::exact);
          const RWWSubString
          ssssuuuubbbbSSSSttttrrrriiiinnnngggg(const wchar_t* cs, size_t start=0,
                    caseCompare = RWWString::exact) const;


     Returns a substring representing the first occurrence of the null-
     terminated string pointed to by "ccccssss".  Case sensitivity is according to
     the ccccaaaasssseeeeCCCCoooommmmppppaaaarrrreeee argument; it defaults to RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt.  The first
     variant can be used as an lvalue.

              RWCString
          ttttooooAAAAsssscccciiiiiiii() const;


     Returns an RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg object of the same length as self, containing only
     ASCII characters.  Any non-ASCII characters in self simply have the high
     bits stripped off.  Use iiiissssAAAAsssscccciiiiiiii(((()))) to determine whether this function is
     safe to use.

              RWCString
          ttttooooMMMMuuuullllttttiiiiBBBByyyytttteeee() const;




                                                                       PPPPaaaaggggeeee 11113333






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     Returns an RRRRWWWWCCCCSSSSttttrrrriiiinnnngggg containing the result of applying the standard C
     library function wwwwccccssssttttoooommmmbbbbssss(((()))) to self.  This function is always safe to
     use.

              void
          ttttooooLLLLoooowwwweeeerrrr();


     Changes all upper-case letters in self to lower-case.  Uses the C library
     function ttttoooowwwwlllloooowwwweeeerrrr(((()))).

              void
          ttttooooUUUUppppppppeeeerrrr();


     Changes all lower-case letters in self to upper-case.  Uses the C library
     function ttttoooowwwwuuuuppppppppeeeerrrr(((()))).

SSSSttttaaaattttiiiicccc PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              static unsigned
          hhhhaaaasssshhhh(const RWWString& wstr);


     Returns the hash value of wwwwssssttttrrrr as returned by
     wwwwssssttttrrrr....hhhhaaaasssshhhh((((RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::eeeexxxxaaaacccctttt)))).

              static size_t
          iiiinnnniiiittttiiiiaaaallllCCCCaaaappppaaaacccciiiittttyyyy(size_t ic = 15);


     Sets the minimum initial capacity of an RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg, and returns the old
     value.  The initial setting is 15 wide characters. Larger values will use
     more memory, but result in fewer resizes when concatenating or reading
     strings. Smaller values will waste less memory, but result in more
     resizes.

              static size_t
          mmmmaaaaxxxxWWWWaaaasssstttteeee(size_t mw = 15);


     Sets the maximum amount of unused space allowed in a wide string should
     it shrink, and returns the old value.  The initial setting is 15 wide
     characters.  If more than mmmmwwww characters are wasted, then excess space
     will be reclaimed.

              static size_t
          rrrreeeessssiiiizzzzeeeeIIIInnnnccccrrrreeeemmmmeeeennnntttt(size_t ri = 16);


     Sets the resize increment when more memory is needed to grow a wide
     string.  Returns the old value.  The initial setting is 16 wide




                                                                       PPPPaaaaggggeeee 11114444






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



     characters.

RRRReeeellllaaaatttteeeedddd GGGGlllloooobbbbaaaallll OOOOppppeeeerrrraaaattttoooorrrrssss
              RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr========(const RWWString&, const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr!!!!====(const RWWString&, const RWWString&);


     Logical equality and inequality.  Case sensitivity is eeeexxxxaaaacccctttt.

              RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<< (const RWWString&, const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>> (const RWWString&, const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr<<<<====(const RWWString&, const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const RWWString&, const wchar_t*  );
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const wchar_t*,   const RWWString&);
          RWBoolean
          ooooppppeeeerrrraaaattttoooorrrr>>>>====(const RWWString&, const RWWString&);


     Comparisons are done lexicographically, byte by byte.  Case sensitivity
     is eeeexxxxaaaacccctttt.  Use member ccccoooollllllllaaaatttteeee(((()))) or ssssttttrrrrxxxxffffrrrrmmmm(((()))) for locale sensitivity.

              RWWString
          ooooppppeeeerrrraaaattttoooorrrr++++(const RWWString&, const RWWString&);
          RWWString
          ooooppppeeeerrrraaaattttoooorrrr++++(const wchar_t*,   const RWWString&);



                                                                       PPPPaaaaggggeeee 11115555






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



          RWWString
          ooooppppeeeerrrraaaattttoooorrrr++++(const RWWString&, const wchar_t*  );


     Concatenation operators.

              ostream&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(ostream& s, const RWWString& str);


     Output an RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg on ostream ssss.  Each character of ssssttttrrrr is first
     converted to a multibyte character before being shifted out to ssss.

              istream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(istream& s, RWWString& str);


     Calls ssssttttrrrr....rrrreeeeaaaaddddTTTTooookkkkeeeennnn((((ssss)))).  That is, a token is read from the input stream
     ssss.

              RWvostream&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWvostream&, const RWWString& str);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr<<<<<<<<(RWFile&,     const RWWString& str);


     Saves string ssssttttrrrr to a virtual stream or RRRRWWWWFFFFiiiilllleeee, respectively.

              RWvistream&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWvistream&, RWWString& str);
          RWFile&
          ooooppppeeeerrrraaaattttoooorrrr>>>>>>>>(RWFile&,     RWWString& str);


     Restores a wide character string into ssssttttrrrr from a virtual stream or
     RRRRWWWWFFFFiiiilllleeee, respectively, replacing the previous contents of ssssttttrrrr.

RRRReeeellllaaaatttteeeedddd GGGGlllloooobbbbaaaallll FFFFuuuunnnnccccttttiiiioooonnnnssss
              RWWString
          ssssttttrrrrXXXXFFFFoooorrrrmmmm(const RWWString&);


     Returns a string transformed by ::::::::wwwwssssxxxxffffrrrrmmmm(((()))), to allow quicker collation
     than RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg::::::::ccccoooollllllllaaaatttteeee(((()))).

              RWWString
          ttttooooLLLLoooowwwweeeerrrr(const RWWString& str);


     Returns a version of ssssttttrrrr where all upper-case characters have been
     replaced with lower-case characters.  Uses the C library function
     ttttoooowwwwlllloooowwwweeeerrrr(((()))).



                                                                       PPPPaaaaggggeeee 11116666






RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))                                                RRRRWWWWWWWWSSSSttttrrrriiiinnnngggg((((3333CCCC++++++++))))



              RWWString
          ttttooooUUUUppppppppeeeerrrr(const RWWString& str);


     Returns a version of ssssttttrrrr where all lower-case characters have been
     replaced with upper-case characters. Uses the C library function
     ttttoooowwwwuuuuppppppppeeeerrrr(((()))).
















































                                                                       PPPPaaaaggggeeee 11117777